home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / MODULES / THSND.ZIP / !Help next >
Text File  |  1997-09-19  |  5KB  |  149 lines
  1. THSound
  2. =======
  3. by:
  4.  
  5. Tony Houghton
  6. 271 Upper Weston Lane
  7. Southampton
  8. SO19 9HY
  9.  
  10. tonyh@tcp.co.uk
  11. http://homepages.tcp.co.uk/~tonyh/
  12.  
  13. Version 1.21
  14.  
  15. The purpose of THSound is to allow many different samples to be played
  16. without having to load each one as a module in its own right (often
  17. impractical due to potential name clashes). All it does is take a pointer to
  18. some data in raw 8-bit VIDC format and use this to make a sound voice.
  19. THSound is deliberately very basic for flexibility. It is up to your program
  20. to manage memory for the sample data, and to attach the voice to channels and
  21. play it using the standard Sound SWIs.
  22.  
  23. I wrote THSound because I was writing a program which needed to play a large
  24. number of samples, the data for these being embedded in large files with
  25. other resources. I couldn't find a PD program which could do what I wanted
  26. (other modules only seem to be able to load samples as files) so I studied
  27. the PRM and THSound was born.
  28.  
  29. Conditions of use
  30. -----------------
  31. THSound may be freely distributed. It may be used in applications provided it
  32. is unaltered and you credit me, the author. If possible, please include this
  33. file with it (I know that won't always be possible), or at least indicate
  34. that it is available with instructions from PD libraries. As a courtesy it
  35. would be very nice if you send me copies of any programs you write which use
  36. it.
  37.  
  38. Technical details
  39. =================
  40. THSound contains three SWIs for sound sample handling; its SWI chunk is
  41. &4B780 (officially registered with Acorn).
  42.  
  43. SWI's
  44. -----
  45. THSound_InstallSample        &4b780
  46. Entry:    R0 = Address of sample (in VIDC 8-bit signed log format)
  47.     R1 = Size of sample in bytes (word aligned)
  48.     R2 = Slot to install in or 0 for next free slot (see
  49.         Sound_InstallVoice)
  50. Exit:    R0 = Sample's "handle" (pointer to workspace)
  51.     R1 = Voice slot sample is installed in
  52.     R2 = Voice slot (copy of R1)
  53.  
  54. It is recommended that sample data is kept in the RMA, using OS_Module for
  55. memory management (Archimedes), or in a dynamic area (Risc PC). Having sample
  56. data in application workspace could crash SoundDMA if the application is
  57. paged out eg by Wimp_Poll while the sample is playing.
  58.  
  59. Each sample's voice is given the name THSVoice<hh> where <hh> is a unique hex
  60. code.
  61.  
  62.  
  63. THSound_RemoveSample        &4b781
  64. Entry:    R0 = Sample's handle
  65. Exit:    R0   Preserved
  66.  
  67. Use this to kill a THSound sample, do not use Sound_RemoveVoice. The sample's
  68. data is not freed, just its workspace (handle) allocated when it was
  69. installed.
  70.  
  71.  
  72. THSound_GetVoiceSlot        &4b782
  73. Entry:    R0 = Sample's handle
  74. Exit:    R0   Preserved
  75.     R1 = Voice slot
  76.  
  77. Finds the sample's voice slot in case you haven't stored the value returned
  78. by THSound_InstallVoice.
  79.  
  80.  
  81. THSound_ChannelInUse        &4b783
  82. Entry:    R0 = Channel number
  83. Exit:    R0   Non-zero if a THSound sample is playing on specified channel.
  84.  
  85. New in version 1.10, remember to check the version if you use this SWI.
  86.  
  87. This reads data from the SCCB to test whether a THSound voice is
  88. currently playing (it won't work for most other samples, because THSound
  89. uses the SCCB in a slightly non-standard way). The necessary information
  90. in the SCCB is invalid immediately after calling Sound_Control and may
  91. wrongly show the channel not to be in use, so if you want to wait for a
  92. channel to become free you should use something like:
  93.  
  94.   REM First wait for SCCB to be updated, showing channel is in use
  95.   REPEAT
  96.   SYS"THSound_ChannelInUse",1 TO inuse%
  97.   UNTIL inuse%
  98.   REM Now wait until channel is free
  99.   REPEAT
  100.   SYS"THSound_ChannelInUse",1 TO inuse%
  101.   UNTIL NOT inuse%
  102.  
  103. The second loop can be after, say, a Wimp_Poll, but I suggest you put
  104. the first loop immediately after a Sound_Control (or similar)
  105. instruction.
  106.  
  107. THSound_GetPollWord        &4b784
  108. Entry:    R0 = Sample's handle
  109. Exit:    R0   Preserved
  110.     R1 = (Pointer to) poll word
  111.  
  112. New in version 1.20
  113.  
  114. This is more useful than THSound_ChannelInUse for multitasking programs.
  115. Before playing a sample you can set the pollword to 0, and it will be
  116. altered when the sample finishes playing or is interrupted by being detached
  117. from its channel. Therefore you can use PollWordNonZero Wimp events to
  118. receive notification.
  119.  
  120. If the sample finishes playing without being interrupted, -1 or &FFFFFFFF
  121. will be written to the pollword, otherwise another non-zero value will be
  122. written.
  123.  
  124. THPlay
  125. ======
  126. THPlay is a short BASIC program that can be used to play a sample in the
  127. background. It must be given a file containing raw sample data in 8-bit VIDC
  128. format, using the -file parameter in its command line. THPlay loads the
  129. sample into the RMA, starts playing it, then polls the Wimp until it has
  130. finished playing or a time limit is reached. Then THPlay releases the sample
  131. and its memory and quits.
  132.  
  133. Other parameters are optional and are:
  134.  
  135. Parameter    Default    Meaning
  136. ---------    -------    -------
  137. -chan        1    Channel to play sample on
  138. -vol        &17F    Volume to play sample at
  139. -pitch        &2000    Pitch to play sample at
  140. -maxtime    10    Maximum time in seconds before sample is killed
  141.  
  142. THPlay requires at least a 12K WimpSlot. You might like to run it via an Obey
  143. file to ensure THSound gets loaded first and that THPlay isn't allocated an
  144. unnecessarily large Wimpslot. For example:
  145.  
  146. RMEnsure THSound 1.20 RMLoad <Obey$Dir>.THSound
  147. WimpSlot -min 12k -max 12k
  148. <Obey$Dir>.THPlay -pitch &3000 -file %0
  149.